reStructuredText 规范

rst 写作指南

  • 为了形成良好的风格，这里建议使用 editorconfig 对文本进行自动规范化。一个简单的 editorconfig 内容如下：

    root = true

[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8
indent_style = space
indent_size = 4

[*.rst]
indent_size = 3

    rst 应当是三个空格对齐，这点与代码文件的双空格或四空格对齐不同

  • 当需要指示某一部分是对另一部分的详细说明时，对详细部分进行缩进。缩进内容与未缩进内容保持一个换行符的间隔

  • 当在文中引用复杂的 ASCII 表格表示法时，应当将编辑器的文字设置为 含中文的等宽字体 ，例如 Noto CJK SC Mono

  • 当引用的链接中含有空格时，统一使用反转义的格式进行标识。这样即使是在 Latex 中也能正确识别

  • 对于数学公式而言，需要对齐的公式环境中，例如 begin{array}{lc} ，这里的对齐声明 {lc} 必须根据实际填写，否则 latex 编译会失败。

  • 在段落块、列表块、公式块、代码块、Note 块等块之间，使用 一个 换行符隔离

  • 由于 "``" 语法在 Latex 环境中没法显现出来，因此应当尽量使用粗体、斜体。

  • 由于中文没有斜体，所有 Latex 普通字号和斜体的区别只是字体不一样，所以尽量不要再中文中使用斜体

  • 脚注、引用等直接放在小节的后面，而不是全文的末尾。这样在后续修改的时候比较方便

  • 不要使用 [#] ，而要使用 [#note]

  • 不要使用 svg 和 jepg 后缀名的图片，这些图片 Latex 无法通过编辑

  • 数学公式中的下划线需要被反转义才能被 latex 编译，但是这样会导致网页版的显示有问题，所以建议在公式中不要带下划线

空白字符

空格或者 tab 一般用于 缩进 。tab 一般会转换为空格。

其他空白字符（换页符、垂直 tab）会在被处理之前被转换为一个空格。

空行

空行用于分割段落和其他元素。除非是字面量中的空行外（这里所有的空白字符都被保留），多个连续的空行被视为一个空行。当标记能明显区分元素时，空行可以被省略。文档的开头和结尾总是被视为存在空行（即使它没有）。

缩进

缩进一般使用三个空格

转义机制

rst 使用反斜杠进行转义。

  • 在 URI 上下文中[1] ，转义的空格代表单个空格

引用名

引用名标识了交叉引用的元素。

对于简单引用而言，空白字符是允许的。多个的空白字符被视为单个空格：

Want to learn about `my favorite programming language`_?
.. _my favorite programming language: http://www.python.org

以下形式相同：

- `A HYPERLINK`_
- `a    hyperlink`_
- `A
  Hyperlink`_

文档结构

文档的根元素是 “document” 。一个文档包含以下三种元素： body 元素 、 transition 元素 和 section 。

rst 无法显式指定文章的副标题或标题

section

section 通过它的标题进行识别。标题由一行文本加上一行长度不少于文本的连续的相同字符组成，字符可为下列一种：

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [  ] ^ _ ` { | } ~

以下字符更推荐被使用：

= - ` : . ' " ~ ^ _ * + #

在一个文档中先出现的字符行被视为一级标题，以此类推。

section 有两种表示方式：

===============
Section Title
===============

Section Title
-------------

标题后是否加入一个空行是可选的，但是推荐加入

一般而言

\#用于编
\*用于章
=用于节
-用于小节
^用于子小节
"用于款

标题会自动生成一个可链接的目标。

transition

transition 被用于生成一个分割线用来分割文章。

Para.

----------

Para.

body 元素

段落

段落是一段左对齐的文本，可含有 内联标记 。段落和段落之间由空行分割。

无序列表

以 *、+、-、•、‣、⁃ 开头，其后跟随一个空格的行被视为无序列表。无序列表之间需要使用空行分割、需要使用 缩进 表示级别关系：

- item 1
- item 2
- item 3

   - subItem 1
   - subItem 2

枚举列表

可以使用罗马数字、大写或小写的英文字母、大写或小写的希腊字母（会被转换为数组）定义枚举列表。或者使用 # 自动编号。

以下形式被视为合法形式：

1.
(1)
1)

例如：

1. 从四开始编号
#. 自动编号
#. 自动编号
#. 自动编号

定义列表

定义列表由一个标题加上一个英文冒号（可选）加上一个 缩进 的 段落 组成：

term 1
   Definition 1.

term 2
   Definition 2, paragraph 1.

   Definition 2, paragraph 2.

term 3 : classifier
   Definition 3.

term 4 : classifier one : classifier two
   Definition 4.

字段列表

:Date: 2001-08-16
:Version: 1
:Authors: - Me
         - Myself
         - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

对于文献，有以下额外字段：

Field name

doctree element

Abstract

topic

Address

address

Author

author

Authors

authors

Contact

contact

Copyright

copyright

Date

date

Dedication

topic

Organization

organization

Revision

revision

Status

status

Version

version

选项列表

选项列表用于表示命令行参数：

-a         Output all.
-b         Output both (this description is
         quite long).
-c arg     Output just arg.
--long     Output all day long.

-p         This option has two paragraphs in the description.
         This is the first.

         This is the second.  Blank lines may be omitted between
         options (as above) or left in (as here and below).

渲染结果如下：

-a Output all. -b Output both (this description is quite long). -c arg Output just arg. --long Output all day long.

-p This option has two paragraphs in the description.

This is the first. + This is the second. Blank lines may be omitted between options (as above) or left in (as here and below).

原始字面量块

以两个冒号开始的块代表原始字面量。其中的任何字符都不会被转义。

::

   for a in [5,4,3,2,1]:   # this is program code, shown as-is
      print a
   print "it's..."
   # a literal block continues until the indentation ends

以下形式都是可以接受的：

::

   Literal block

Paragraph: ::

   Literal block

Paragraph::

   Literal block

行块

使用竖杠起始的被视为行块，行块中的空白字符不会被转义

| A one, two, a one two three four
|
| Half a bee, philosophically,
|     must, *ipso facto*, half not be.
| But half the bee has got to be,
|     *vis a vis* its entity.  D'you see?
|
| But can a bee be said to be
|     or not to be an entire bee,
|         when half the bee is not a bee,
|             due to some ancient injury?
|
| Singing...

块引用

被 缩进 的文本块被视为对一段文字的引用：

This is an ordinary paragraph, introducing a block quote.

   "It is my business to know things.  That is my trade."

   -- Sherlock Holmes

渲染结果如下：

This is an ordinary paragraph, introducing a block quote.

"It is my business to know things. That is my trade."

 — Sherlock Holmes

多个块引用之间通过空行分割。

空 注释 可被用于显式的中断前文的结构，或者用来分割块引用

文档测试块

使用 >>> 开头的文本块将通过 python 的 doctest 模块 提供强大的测试环境。

>>> print("hello, world")

表格

网格表

网格表提供了最大限度的表格支持。包括表的跨行和跨列。

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+
简单表

简单表提供简单的跨行和跨列支持

=====  =====  =======
A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
=====  =====  ======
   Inputs     Output
------------  ------
A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======
=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
      Second line of paragraph.
3      - Second column of row 3.

      - Second item in bullet
         list (row 3, column 2).
      Row 4; column 1 will be empty.
=====  =====
CSV 表格

csv 表格属于 Sphinx 的扩充语法，使用 .. csv:: 定义

显式标记块

显式标记块用于 脚注、引用、超链接目标_、指令_、替换定义_ 和 注释

显式标记是一个文本块：

  • 第一行以 .. 开头，后跟空格

  • 第二行及其后续行相对第一行缩进

  • 在未缩进行之前结束

显式标记块与其他元素之间需要使用空行分割，但是显式标记块之间的空行是可选的

脚注

脚注由 ..空格[标签]+空格 四部分组成。后跟缩进的正文。标签可以是：

  • 十进制整数

  • 使用 # 表示 自动编号脚注

  • 一个 # 接一个简单的参考名称（一个 自动编号标签）

  • 单个 * 表示 自动符号脚注

例如：

  • 手动编号脚注：

    .. [1] Body elements go here.

  • 自动编号脚注：

    If [#note]_ is the first footnote reference, it will show up as
"[1]".  We can refer to it again as [#note]_ and again see
"[1]".  We can also refer to it as note_ (an ordinary internal
hyperlink reference).

.. [#note] This is the footnote labeled "note".

  • 自动符号脚注

    Here is a symbolic footnote reference: [*]_.

.. [*] This is the footnote.

    也可以第一个使用手动编号以暗示下面编号的顺序

    [2]_ will be "2" (manually numbered),
[#]_ will be "3" (anonymous auto-numbered), and
[#label]_ will be "1" (labeled auto-numbered).

.. [2] This footnote is labeled manually, so its number is fixed.

.. [#label] This autonumber-labeled footnote will be labeled "1".
   It is the first auto-numbered footnote and no other footnote
   with label "1" exists.  The order of the footnotes is used to
   determine numbering, not the order of the footnote references.

.. [#] This footnote will be labeled "3".  It is the second
   auto-numbered footnote, but footnote label "2" is already used.
引文

引文与 脚注 类似。但是其标签中填写的任意内容：

Here is a citation reference: [CIT2002]_.

.. [CIT2002] This is the citation.  It's just like a footnote,
   except the label is textual.
超链接目标

超链接目标也叫做 显式超链接目标，与 匿名超链接目标 相对应。

使用方式为：

hyperlink-name_

.. _hyperlink-name: link-block

如果 hyperlink-name 中包含冒号，则可以使用反引号对齐进行包裹，或者使用反斜杠进行转义。

link-block 是可选的，文档中可以使用此命令来生成一个不可见的锚点

匿名超链接目标

用法为：

See `the web site of my favorite programming language`__.
.. __: anonymous-hyperlink-target-link-block

或

__ anonymous-hyperlink-target-link-block
指令
替换定义

例如：

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png
注释

以两个点开头的内容被视为注释。不会被显示出来：

.. This is a comment

内联标记

斜体

使用 * 包裹的文字是斜体

粗体

使用 ** 包裹的文字是粗体

内联字面量

使用 `` 包裹的被视为内联字面量。

数学公式

Sphinx 使用 AmSMath LaTex package 。

1. 在 URI 上下文（ 外部超链接 或 图像的指令参数）中，空格一般被省略
Last moify: 2022-12-04 15:11:33
Build time：2025-07-18 09:41:42
Powered By asphinx